Введение

Этот материал помогает аналитикам описывать и проверять требования к доступу в системе: от входа пользователя до контроля прав. Если тебе нужно быстро развести термины, см. также файл auth-vs-auth.

Важно разделять два слоя:

Базовый словарь

Токены: Access и Refresh

Во многих API используется двухтокенная схема. После успешного входа система выдает временные ключи (токены), чтобы клиент мог обращаться к защищенным ресурсам без повторного ввода пароля.

Тип токена Назначение Время жизни Безопасность
Access Token Доступ к ресурсам (API, данные профиля). Короткое (например 5–30 минут) Обычно передается в заголовке Authorization: Bearer <token>; на клиенте предпочтительно хранить в памяти приложения, чтобы снизить риск XSS-кражи.
Refresh Token Получение нового access token, когда старый истек. Длинное (например 7–30 дней) Типично хранится в защищенном контейнере (часто HttpOnly cookie) и используется только для обращения к эндпоинту обновления.

Ключевой смысл: access token живет мало, поэтому его компрометация ограничена по времени. refresh token живет долго, поэтому к нему требования строже (ротация, отзыв, привязка к устройству/сессии).

Пароли: хранение и проверка

⚠️ Никогда не храните пароли в открытом виде!

Пароли должны проходить через процесс хэширования – одностороннего криптографического преобразования. Популярные и надежные алгоритмы – bcrypt и Argon2.

Что важно для аналитика в требованиях:

2FA/MFA и OTP

Для повышения безопасности используется двухфакторная аутентификация (2FA). Это метод, требующий подтверждения личности двумя разными способами:

  1. Фактор знания: то, что вы знаете (пароль).
  2. Фактор владения: то, чем вы владеете (телефон для получения SMS).

OTP (One-Time Password) — одноразовый код, действующий короткое время (обычно 30–300 секунд). Практически встречаются:

Что стоит зафиксировать в требованиях:

Как описывать HTTP и SQL в sequence-диаграммах

Sequence-диаграмма удобна, чтобы согласовать поведение фронта/бэка/БД и проговорить ошибки.

Участники

Как подписывать сообщения

Типовые фреймы

Пример: логин + выдача токенов (Mermaid)

sequenceDiagram
    participant User
    participant App
    participant Auth as Auth Service
    participant DB as Database

    App->>Auth: POST /api/v1/auth/login {email, password}
    Auth->>DB: SELECT id, password_hash, status FROM users WHERE email = ?
    alt user exists and password ok
        Auth->>DB: INSERT INTO refresh_tokens (user_id, token_hash, expires_at, device_id) VALUES (...)
        Auth-->>App: 200 OK {access_token, refresh_token}
    else invalid credentials
        Auth-->>App: 401 Unauthorized
    else user blocked
        Auth-->>App: 403 Forbidden
    end

Таблица HTTP-статусов (аутентификация/авторизация)

Код Название Когда использовать
200 OK Успех Успешный вход, обновление токена, получение профиля.
201 Created Создано Регистрация пользователя, создание сессии/устройства (если моделируется как ресурс).
204 No Content Нет содержимого Успешный logout (если тело ответа не требуется).
400 Bad Request Неверный запрос Не хватает обязательных полей, неверный формат payload.
401 Unauthorized Не аутентифицирован Неверный пароль, отсутствует/невалиден/истек access token.
403 Forbidden Запрещено Аутентификация есть, но прав на действие нет (RBAC/ABAC), или пользователь заблокирован.
409 Conflict Конфликт Попытка зарегистрировать email, который уже существует (если так принято в продукте).
429 Too Many Requests Слишком много запросов Rate limiting, защита от brute force/credential stuffing.

Основные SQL-операции, которые обычно встречаются

Операция Пример SQL Зачем это нужно
Создание пользователя INSERT INTO users (...) VALUES (...) Регистрация.
Поиск пользователя SELECT id, password_hash, status FROM users WHERE email = ? Вход в систему.
Фиксация неуспешной попытки UPDATE users SET failed_attempts = failed_attempts + 1 WHERE id = ? Anti-bruteforce, блокировки.
Сохранение refresh token INSERT INTO refresh_tokens (...) VALUES (...) Создание «длинной» сессии/устройства.
Ротация refresh token UPDATE refresh_tokens SET token_hash = ?, rotated_at = ? WHERE id = ? Снижение риска при компрометации.
Отзыв токенов DELETE FROM refresh_tokens WHERE user_id = ? Logout «со всех устройств» или отзыв при инциденте.

Правила безопасности (и что важно не перепутать)

Риск/угроза Типовые меры защиты
Brute force / credential stuffing Rate limiting, CAPTCHA по риск-сигналам, блокировки/заморозка, уведомления, мониторинг.
CSRF Актуально, когда аутентификация опирается на cookies: SameSite, CSRF-токены, запрет кросс-сайтовых запросов где возможно. Если access token передается только в Authorization header, CSRF-риски обычно ниже, но XSS важнее.
XSS Экранирование/санитизация, CSP, минимизация хранения токенов в доступных JS-хранилищах. HttpOnly cookie защищает от чтения токена JS-кодом, но не является «лекарством от XSS» в целом.
SQL Injection Параметризованные запросы/ORM, валидация входных данных.
Кража refresh token Хешировать refresh token в БД, привязка к устройству, ротация, обнаружение повторного использования (reuse detection).

Чек-лист для аналитика

Связанные темы